
<html><head><title>Template Scripting</title></head>
<body bgcolor="white" text="black">

<table width="95%">
<tr><td width="70%"><h1>Template Scripting<hr></h1></td>
     <td align="right"><a href="guts.html">BACK</a> |
                       <a href="index.html">UP</a> |
                       <a href="tools.html">NEXT</a></td></tr>
<tr><td>

WebMacro's script language was designed to work fluidly with 
HTML and XML. It can also be used to generate other formats, 
such as RTF and WAP. The script syntax is largely orthogonal
to XML and HTML, so that it can be used to generate tags and
portions of tags witout conflicting with the tag syntax itself.
<p>
A WebMacro template is a file containing arbitrary text as 
well as WebMacro directives and variable references. When executed,
the template is passed a Context containing the per-request data
that should be displayed via the template.
<p>
WebMacro will replace variables in the template with values extracted
from the context. There are also a set of directives which can be used to
control the contents of the page: repeating blocks, conditional inclusion,
including or parsing in other files.


<h2>Variables</h2>

Variables are the basic way you access information in the context that's
been supplied to you. Most are quite simple, though some can be fairly 
complex. Here are some examples:
<pre>
   $query
   $Search.Link
   $Ad.Large.findBanner($query).URL
</pre>
Each of these variables refers to an object somewhere in the context. It's
WebMacro's job to figure out how to find the object referred to; it's the 
application programmers job to make sure that it's there. 
<p>
The fundamental contract between a template author and a prorammer 
is a specification of what will appear in the context for a 
particular template.
<p>
The WebMacro servlet environment provides you with a number of standard 
variables and objects pre-defined, in addition to those that the back 
end programmer created. Check the WebContext documentation for more 
information on what's available.
<p>
You can cleanly separate your variable from the surrounding text
by writing it this way: sometext$(foo)moretext. Also, if you need
to write a $ in your text you can escape it: sometext\$foomoretext.
<p>
$ is never recognized as a variable if it is followed by a number,
so you can safely write $10 in your template.


<h2>Directives</h2>

Directives are WebMacro statements that perform some operation; 
conditionally include text; or repeat a block within your template.
<p>
Directives all begin with a '#' character, and must be the first thing 
appearing on a line (they may have optional whitespace in front of them).
<p>
Many directives operate on a block. A block begins with a { and continues
up until a matching } closes it. The closing } character will only be 
recognized if it appears at the start of a line.
<p>
Alternately, you can use #begin and #end instead of { and }, if
you prefer that syntax. As with variables a # is not recognized 
if it is followed by a number, so you can safely write #10; and
also you can use the \ character to escape the # if you need it
in some other context.
<p>
Here's an overview of the available directives.
<p>

<h4><font color="green">## <i>comments</i></font></h4>

Two (or more) #'s at the start of a line form a comment. The rest of 
the line is ignored. The comment may be preceeded by some whitespace,
but otherwise is only recognized at the start of a line. 
<p>
Here's an example:
<pre>
    ## this is a comment
</pre>
<p>


<h4><font color="green">#foreach <i>$thing</i> in <i>list</i></font></h4>

The #foreach directive is the way you create tables and lists in 
WebMacro. #foreach iterates through a list, including its output block
once for each element in the list.
<p>
Here's an example:
<pre>
   &lt;ul&gt;
   #foreach $link in $searchResult {
      &lt;li&gt;$link.Name lives at $link.URL
   }
   &lt;/ul&gt;
</pre>

Each time through the list the variable $link takes on the value 
of the next object in the $searchResult list. 
<p>
You may create the list yourself using the #set statement, or put the
list here directly with [] syntax like this:
<pre>
   #set $list = [ "one", "two", "three" ]
</pre>

More likely the servlet programmer has provided the list for you by
placing it in your context.
<p>
You can put anything you like inside the block for your #foreach
directive: even more #foreach directives. WebMacro can nest them
as deep as you like.
<p>

<h4><font color="green">#if (<i>condition</i>) { ... } #else { ... }</font></h4>

Use the #if directive to conditionally include text. The text is included 
if the condition is true, and not include if it is false.
<p>
In WebMacro, a condition is true if it is defined and has a non-null value
other than Boolean.FALSE. Since WebMacro automatically converts to and
from primitive boolean types, you are encouraged to use boolean values
in conditions whenever possible.
<p>
#if directive conditions can make use of the boolean operators:
<b>&&</b> (and),  <b>||</b> (or), and the unary operator <b>!</b>
(not). These boolean ooerators mean the same thing they do in
Java. They are left-associative, and short circuiting (meaning
the right operand is evaluated only if it has to be).
<p>
You can also use the boolean operators <b>==</b> (equals)
and <b>!=</b> to compare objects. These do not behave like
Java operators do: they rely on Object.equals() rather
than object identity to determine equivalence.
    <p>
Finally, you can group expressions based on Terms and these five
operators using parentheses, as you would expect. Thus the following
is a valid condition: (($User && $User.isOK()) || ($Magic == "foo"))

<p>
Here's an example:
<pre>
    #if ( $Customer.owesMoney() && ($Customer.Name != "Fred") ) 
    {
        Pay up, or else!
    } #else {
        Thank you for your patronage.
    }
</pre>

The #else block is optional--you can leave it off.


<h4><font color="green">#include <i>file</i></font></h4>

Use the #include directive to read in a file. The contents of the 
file will not be parsed, so this is a good way to include JavaScript and
other things that might conflict with WebMacro. 
<p>
You can also use it to read in standard block of HTML which you would 
like to include in every page.
<p>
Here is an example:
<pre>
   #include /web/script/banner.html
</pre>

If you like you can use a full URL as the target for an #include.


<h4><font color="green">#parse <i>file</i></font></h4>

The #parse directive includes a target file and parses it as though it
were part of the current template. 
<p>
You can use this to include common template code that may be shared 
among several different templates.
<p>
Here are some examples:
<pre>
   #parse "/webmacro/library/banner.wm"

   #set $library = "/webmacro/library"
   #parse "$library/banner.wm"
</pre>

Note that you must normally specify an absolute path to the target,
or a URL. This restriction will likely be lifted shortly.


<h4><font color="green">#set <i>$property</i> = <i>value</i></font></h4>

Just as you can access values in the context, you can set them. 
<p>
Here is a simple use of the #set keyword:
<pre>
    #set name = "Fred Flinstone"
    Hi my name is $name
</pre>

The #set directive is much more poweful than this simple use, however. It
can also be used to set properties on complicated objects--if there is a 
way to do it: 
<pre>
   #set $Customer.name = "Sidney"
   #set $Database.findItem($partNum).Description = $newDescription
</pre>

Whether or not it is possible for you to set a value depends on the 
public methods available on the target object. WebMacro will use normal 
Variable reference evaluation to evaluate all but the last term specified
in the left hand side of the #set. Then it will introspect the final object
to determine if it's possible to set the value in some way.
<p>
Refer to the PropertyOperator documentation for a complete list of the 
mechanisms by which WebMacro can succeed in setting a value.


<h2>Just Rendering Logic</h2>

WebMacro's script language is fairly powerful--but it is completely 
focussed on formatting and laying out a page. 
<p>
As a designer you will have to learn some simple scripting. However, it 
should never be very complicated, and it is always related to what you 
are trying to do: lay out information on a page.
<p>
All programming issues, the creation and manipulatio of information, are 
expected to be handled by the programmer in Java.
<p>
As a programmer you may be surprised that WebMacro is lacking more 
sophisticated programming structures. This is intentional. You have 
an excellent, full fledged language--Java--in which to write your 
back end code. 
<p>
Because Webmacro separates all the programming out of the template, both
the program and the HTML templates are much more elegant and understandable
than when those two worlds collide in one document.
<p>
In addition, because they are separate, programmers and page designers 
can work on a project simultaneously. 

</td></tr>
<tr><td><hr></h1></td>
     <td align="right"><a href="guts.html">BACK</a> |
                       <a href="index.html">UP</a> |
                       <a href="tools.html">NEXT</a></td></tr>
</table>
</body></html>
